
                                        17 September 1993

Undocumented DOS READ.ME
~~~~~~~~~~~~~~~~~~~~~~~~

    Here are some notes about the files on the disk that accompanies
UNDOCUMENTED DOS, 2nd edition, by Andrew Schulman, Ralf Brown, Jim
Kyle, David Maxey, and Ray Michels (published by Addison-Wesley,
1993).


    INSTALL
    ~~~~~~~

    Please install the Undocumented DOS software with the INSTALL or
SETUP batch file provided on the disk. We compressed everything
using an unusual set of PKZIP switches (see below), so you should let
the batch files do everything for you. You will need about five
megabytes of hard-disk space. To run INSTALL (or SETUP), specify the
floppy drive you are installing from, and the hard-disk directory you
are installing into. For example:

A:\>install a: d:\undoc2


    What's New?
    ~~~~~~~~~~~

    We have made extensive changes to the Undocumented DOS software
since the first edition of this book (which appeared three years
ago!). In addition to adding many entirely-new programs, such as a
large collection of Windows and DPMI programs that use undocumented
DOS, and programs that help disassemble DOS, in the second edition we
have overhauled practically every program from the first edition.
INTRSPY, CMDSPY, and PHANTOM were rewritten from scratch. DEVLOD and
ENVEDT have been greatly improved.

    Of course, we have upgraded all the programs for MS-DOS 5.0 and
6.0. We were also able to do some final testing under a prerelease
version of MS-DOS 7.0 from Microsoft's forthcoming "Chicago"
operating system. We tested everything under the Windows 3.1
Enhanced mode DOS box, with SHARE loaded. Many programs were also
tested in the OS/2 2.x and Windows NT DOS boxes. 

    We made most of the C programs C++ compatible. The programs don't
use any special features of C++, but you can compile them with the
Borland C++ -P option, for example.

    If you are upgrading from the first edition of the book, please
note that Tim Paterson's excellent chapter on the DOS debugger
interface does not appear in the second edition, because Microsoft
documented the interface. Therefore, you may wish to keep your old
\UNDOC\CHAP7 subdirectory. You can delete all other files from the
first edition.

    Some of the programs on the disk have been changed slightly since
the versions printed in the book. For example, \UNDOC2\CHAP3\VMWALK.C
(walk Windows virtual machines from a DPMI or Windows program) was
changed at the last minute.


    Executable Files
    ~~~~~~~~~~~~~~~~

    The disk contains both executable and source versions of most
programs. However, we have not provided source code for INTRSPY and
CMDSPY. Interested readers may contact David Maxey at CompuServe ID
XXXXX,XXXX.

    We built most of the executables using Microsoft C/C++ 7.0.
However, a few were produced with Borland C++. Because the Borland
startup code makes a BIOS INT 1Ah call, these few programs may have
problems running on Japanese PCs.


    Using the Sample Code
    ~~~~~~~~~~~~~~~~~~~~~

    All code samples, in all supplied forms (source, object, and
executable), are copyrighted material and the authors and publishers
reserve all rights to reproduce and distribute them.

    Our primary method of distribution is the book itself. When you
buy a copy of the book, you have also purchased the right to use any
and all of the code samples on the companion diskette(s) on your own
system. You have also, of course, gained the right to use the ideas
illustrated by these samples in your own programs.

    However, we discovered following the publication of the first
edition that for many reasons, both individuals and organizations
needed some means distributing (or obtaining site licenses for) only
portions of the sample programs.

    Requests for permission to distribute or license code generally
fall into one of two major groups: (1) small software firms and
shareware developers who want to bundle one or two of the utility
programs together with their own products, to provide additional
value to their customers, or (2) major industrial concerns who want
to adopt some of the programs as corporate standards and must be
assured of a legal license plus maintenance and bug-fixes for the
life of the utility.

    We have established separate policies for the two groups of
requests. We will permit bundling of specific utilities with
shareware, freeware, or small developer products, on condition that
our copyright notices are preserved and acknowledgement is given in
the bundled documentation, without license fees. Send each such
request via electronic mail to Andrew Schulman, CompuServe 76320,302
or 76320.302@compuserve.com via the Internet, who will respond with
the written permission. Each such request must identify the specific
programs you want to bundle, the product which they will accompany,
and the initial price/license fee you are charging for the total
bundle.

    Those requiring continued maintenance and upkeep of the utilities
should contact Jim Kyle, CompuServe 76703,762 or Internet
76703.762@compuserve.com, to make arrangements for licensing (please
send a CC: to Andrew Schulman). Each such site license will be
negotiated individually, and we will assess nominal fees. Requests
for quotations in this group should specify the programs involved,
the number of copies you want to license, and the interval at which
you will expect updates. Again, electronic mail is the preferred
medium of communication. If you do not have access to electronic
mail, address all questions to:

Andrew Schulman
UNDOC
859 Massachusetts Avenue
Cambridge MA 02139


    Something Wrong with the Disk?
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    If your disk is damaged, or if you need a 5-1/4" disk, please
contact the publisher directly:

Addison-Wesley Publishing Co.
1 Jacob Way
Reading MA 01867
(617) 944-3700


    We Want to Hear From You!
    ~~~~~~~~~~~~~~~~~~~~~~~~~

    The authors of Undocumented DOS would love to hear from you! Many
of the improvements in this second edition are the result of
comments, criticisms, suggestions, and even some praise, from readers
of the first edition. We greatly prefer electronic mail. Please
send any comments on the book to Andrew Schulman, CIS 76320,302
(Internet 76320.302@compuserve.com), who will either answer you
directly or forward your mail to the appropriate author.


    Coming Soon: the UNDOC Newsletter
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    One of the authors (Andrew Schulman) is planning a regular
newsletter to cover important undocumented and little-known
interfaces. This newsletter will be 16-24 pages and will likely come
out once every two months. The newsletter will of course contain
updates of Undocumented DOS and Undocumented Windows. Sample articles
will include:

What is SHARE?  
Disassembling Visual C++ Programs 
Dissecting the Microsoft CD-ROM Extensions (MSCDEX) 
The Undocumented Linear-Executable (LE) File Format 
Examining Pcode in Microsoft C++ 
Undocumented Pentium: Inside the Infamous "Appendix H" 
More Windows Secrets: Undocumented SYSTEM.INI Settings 
The MS-DOS 6.0 Preload API 
What is "Instance Data"?  
Undocumented NT 
Inside DoubleSpace 
How to Disassemble a Virtual Device Driver (VxD)
GDI Internals 
Inside Windows Multimedia: Examining MMSYSTEM.DLL 
Inside the Visual Basic File Format 
What is "Chicago"?  

    For further information on the UNDOC newsletter, please send a
postcard (no email on this one, please!) with your name and address to:

Andrew Schulman
UNDOC
859 Massachusetts Avenue
Cambridge MA 02139


    Other Sources of Information
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Dr. Dobb's Journal is currently running a monthly "Undocumented
Corner," edited by Andrew Schulman. Articles in this column have
included discussions of undocumented INT 21h and INT 2Fh calls
supported by LAN Manager, the Windows PIF file format, the NetWare
Core Protocol (NCP), the Windows HLP file format, and other topics.
Several important updates to "Undocumented Windows" have been
published in this column. For more information about subscribing to
Dr. Dobb's, call 415-358-9500.

    The Windows/DOS Developer's Journal often publishes articles on
undocumented or difficult-to-understand interfaces. For example, a
recent issue included an article on "Getting the Most from Real-Mode
Memory" (HMA, UMBs, stealing video RAM), "Interfacing a Windows
Program to a Real-Mode Device Driver," and "DDE to DOS" (writing a
VxD to allow a DOS program to do Dynamic Data Exchange under
Windows). For more information about subscribing to the Windows/DOS
Developer's Journal, call 913-841-1631.

    Interestingly, Microsoft itself provides a key source of
information on interfaces that programmers often _think_ are
undocumented: the Microsoft Systems Journal. Recent issues have
carried numerous articles by Matt Pietrek and Andrew Schulman on
Windows VxDs, and every issue includes Jeff Prosise's MS-DOS Q&A
column and Paul DiLascia's C/C++ Q&A column. Every issue includes, at
no extra charge, a wonderfully bizarre editor's note. For more
information about subscribing to the Microsoft Systems Journal, call
415-358-9500.

    You may be interested in other books published by Addison-Wesley
as part of what, for want of a better name, is called "The Andrew
Schulman Programming Series":

DOS Internals, by Geoff Chappell. (Coming in late 1993.)  This is the
place to go after you've read Undocumented DOS. Chappell's book
covers in far more detail (and far more accurately!) many topics for
which Undocumented DOS only skims the surface, including DOS/Windows
interaction, the DOS boot sequence, XMS, HIMEM, the A20 line, the
undocumented LOADALL instruction, EMM386, low-level aspects of the
disk, DOS error codes, extended memory, IO.SYS, device drivers, and
so on.

The Undocumented PC, by Frank van Gilluwe. (Coming in late 1993.)
This book provides a fresh, up-to-date look at the standard PC BIOS,
including extensive information on absolute memory locations and I/O
ports. 

Undocumented NetWare, by Tim Farley. (Coming in early 1994.)  
If you thought Microsoft was bad, wait 'til you see all the goodies
that Novell has hidden! Farley covers the NetWare shell, NetWare Core
Protocol (NCP), the NetWare Lite API, the F2 interface, PEP, and more.

DOS: The Source, by Mike Podanoffsky. (Coming 1994.) 
Ever wonder what really happens when you call EXEC?  Mike is the
author of a DOS workalike called RxDOS, and this book presents the
source code for RxDOS, providing a unique inside look at how a DOS
really works. 

The New PC From the Inside Out, 3rd edition, by Murray Sargent III
and Richard Shoemaker. (Coming 1994) 
This is a classic book on the internal workings of the PC, completely
updated to cover protected mode, Windows, 386 memory management,
and a host of other topics. One of the authors was instrumental in
porting Windows to protected mode.

And don't forget...

Undocumented Windows, by Andrew Schulman, David Maxey, and Matt
Pietrek. (Available now.)
Given the strong, and growing, ties between DOS and Windows, it is
not surprising that the book Undocumented Windows has a large amount
of material on DOS. For example, did you know that every Windows
application still has a DOS PSP, located in conventional memory?  If
you liked Undocumented DOS, you'll love Undocumented Windows
(really!). You'll see that Windows isn't as different from DOS as
other books have led you to believe. 

Windows Internals, by Matt Pietrek. (Available now.)
Matt shows in detail how parts of Windows boot up on top of DOS.
If you're reading Undocumented DOS, it's probably because you want
to know how to write cool DOS programs. Well, Windows is a cool DOS
program that uses tons of undocumented DOS calls. Matt's explanation
of Windows internals will greatly enhance your knowledge of DOS.

    
    What's With the Weird ZIP Files?
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    
    Finally, you may wonder why all the Undocumented DOS programs are
compressed on this disk using a strange two-level scheme. For
example, inside UNDOC21.ZIP there is _another_ ZIP file, called
ZIPARCH1.ZIP. This two-level scheme allows us to fit everything on a
single 1.44 megabyte diskette.

    Of course, compressing a bunch of files with PKZIP (or any other
compressor), and then trying to compress the resulting compressed
file again, will _not_ yield a smaller file. Compressing an
already-compressed file is generally impossible because (a) the first
compression stage presumably removed all redundancy from the file;
and (b) otherwise, you would have the information-theory equivalent of
perpetual motion. It ain't possible.

    However, what if the first stage doesn't do any compression? You
simply use PKZIP to archive a bunch of small files together into one
file, and then compress that single file. If there is a fair amount
of redundancy among the original small files, then this two-stage
compression will achieve radically better compression than simply
running PKZIP on the individual small files. 

    Why?  Because PKZIP (or any other compressor) starts compression
all over again with each new file. This lets you extract individual
files out of the larger ZIP. But what if you don't care about the
ability to extract individual files, that is, what if you will
decompress everything at one time?  And what if the individual files
were fairly small and fairly similar to each other? In a case such as
this (which occurs pretty frequently), it's better to first archive
all the small files together, without any compression, and then to
compress the single archive file.

    In other words, PKZIP is normally used as an archiving
compressor: it compresses each file, and then archives it into the
ZIP file. But here, we are using PKZIP as a compressing archiver:
first we archive, then we compress. Run pkzip -e0 to archive into a
single non-compressed file, and then pkzip to compress the one file.

    Undocumented DOS comes with tons of smallish (20k bytes seems to
be the threshhold for PKZIP) files with lots of redundancy, so it's
perfect for this two-level compression. To build the disk, we archive
all the C files together, all the EXE files together, and so on. Then
we compress the archive files. By doing this, we saved about 839k -
534k = 305k bytes. Some of which we've now wasted with this lengthy
explanation.

=== end ===

